From: Snapshot-Content-Location: https://learning.oreilly.com/library/view/securing-the-perimeter/9781484226018/html/425975_1_En_4_Chapter.xhtml Subject: =?utf-8?Q?4.=C2=A0OAuth=20-=20Securing=20the=20Perimeter:=20Deploying=20I?= =?utf-8?Q?dentity=20and=20Access=20Management=20with=20Free=20Open=20Sour?= =?utf-8?Q?ce=20Software?= Date: Sat, 4 Apr 2020 09:39:04 -0000 MIME-Version: 1.0 Content-Type: multipart/related; type="text/html"; boundary="----MultipartBoundary--lmBg0JodqhjrfvZxYiZJFempWbK0478Ox6YcSdoce4----" ------MultipartBoundary--lmBg0JodqhjrfvZxYiZJFempWbK0478Ox6YcSdoce4---- Content-Type: text/html Content-ID: Content-Transfer-Encoding: quoted-printable Content-Location: https://learning.oreilly.com/library/view/securing-the-perimeter/9781484226018/html/425975_1_En_4_Chapter.xhtml 4. OAuth - Securing the Perimeter: Depl= oying Identity and Access Management with Free Open Source Software= !--begin> ">= !--begin> ">= =20 =20 =20

=20

=20 =20 =20

=20

=20 =20

=20

=20 =20 =20 =20

=20 =20 =20 =20 Previous Chapter

3. SAML

=20 =20

=20 =20 =20 =20 Next Chapter

5. OpenID Conne= ct

=20 =20

=C2= =A9 Michael Schwartz, Maciej Machulak 2018

Michael Schwartz and Maciej MachulakSecuring the Perimeterhttps://doi.= org/10.1007/978-1-4842-2601-8_4

4.&n= bsp;OAuth

<= span class=3D"Author">Michael Schwartz¹ and = Maciej Machulak²

(1)Austin, TX, USA

(2)

London, UK

<= /div>

OAuth 2.0 (or simply as =E2=80=9COAuth=E2=80=9D because OAut= h 1.0 is now irrelevant) defines a mechanism for= using bearer tokens to make authorized HTTP requests. Simple possession of= a bearer token enables access. For example, a long time ago in New York Ci= ty, if you had a =E2=80=9Csubway token,=E2=80=9D you inserted it into the t= urnstile and entered the subway station. No questions asked=E2=80=94you hav= e the token, you get in. Bearer tokens are also called =E2=80=9Caccess toke= ns=E2=80=9D.

Although OAuth is known pri= marily as a technology for consumer applications= , its popularity is expanding in enterprise IAM. A common misperception is = that OAuth is a protocol. More accurately, it is a framework for authorizat= ion=E2=80=94a set of foundational patterns and vocabulary. OAuth is not an = authentication protocol. If this were true, OAuth would need to provide spe= cific details, like how messages are sent, the exact data structure of thos= e messages, and how message integrity is assured. Vittorio Bertocci made an= apt analogy in one of his Microsoft blogs for M= icrosoft¹:

OAuth 2.0 as a building blo= ck for implementing a sign-in flow is not only perfectly possible, but quit= e handy too: a LOT of web applications take advantage of that, and it works= great. But that does NOT mean that OAuth is an authentication protocol, wi= th all the affordances you=E2=80=99ve come to expect from one, as much as u= sing chocolate to make fudge does not make (chocolate =3D=3D fudge) true.

Chapter 5 focu= ses on a protocol that uses OAuth to define a sign in flow=E2=80=94OpenID C= onnect. Chapter 8 focuses on another OAuth protocol used for API access Managem= ent=E2=80=94UMA. But in this chapter, we introduce some of the common OAuth= terminology and ideas that to give you some background for what=E2=80=99s = to come.

Scopes

Scopes are used to specify the extent of access for a token. Think= of an airplane boarding pass. Airlines scan your boarding pass before they= let you enter the plane. If the agent sees a green light, they let you pas= s=E2=80=94real-world token validation! On some airlines, not all boarding p= asses are the same. You might prefer a boarding pass that entitles you to s= it in first class. Or your boarding pass may qualify you for a specific sea= t assignment. You can think of scopes as these additional constraints. For = example, a resource server may offer many APIs. The authorization server ma= y use scopes to differentiate which APIs you can access. Even within an API= , certain features may not be available unless you have a token with the ri= ght scope.

Scopes may be any string valu= e, but it=E2=80=99s a common practice to use a URI for scopes. The advantag= e of this practice is that scopes will be less likely to collide. For examp= le, many developers in an organization may want to use a scope called =E2= =80=9Cwrite=E2=80=9D. If each developer uses a different URI namespace for = their =E2=80=9Cwrite=E2=80=9D scope, they will be unique. Google publishes = a list of all their APIs and which scopes are required in order to call the= m. A small excerpt is shown in Figure 4-1.
Figure 4-1
Some Google OAuth scopes

According to Figure 4-1, if you want to call a Google API that allows you to = =E2=80=9Cview and manage your data in Google BigQuery,=E2=80=9D you=E2=80= =99ll need a token with the scope https:= //www.googleapis.com/auth/bigquery . Using this approach, Google uses scopes t= o manage which clients can access which features of their service. Google f= ollows the convention of using URIs for scope values. You may also notice t= hat the APIs are versioned. If an API is updated, new features may be intro= duced, which may require different scopes. Client developers rely on these = scopes and need to know about them before they write their code.

OAuth Roles

You=E2=80=99ll some= times hear OAuth referred to as =E2=80=9Cthree-legged=E2=80=9D. Those legs = are the =E2=80=9Cclient,=E2=80=9D =E2=80=9Cresource server,=E2=80=9D and = =E2=80=9Cauthorization server=E2=80=9D. The client is the software (website= or mobile application) that is either requesting a protected resource or c= onnected to a person requesting a protected web resource. The resource serv= er is the software that has web content that needs protecting, API endpoint= s for example. The authorization server is the software that issues tokens = to a client. Another way to think about OAuth is that the resource server i= s the policy enforcement point (PEP), and the authorization server is the p= olicy decision point (PDP). Figure 4-2 shows the three le= gs, as well as the people who interact with them.
= Figure 4-2
OAut= h roles

Authorization Server
The authorization = server is the most complex component of an OAuth infrastructure. For some d= eployments, the authorization server and the resource s= erver may be one software process. For larger deployments, a central= ized, single-purpose authorization server may issue tokens to control acces= s to a distributed network of resource servers. The authorization server ho= lds client credentials=E2=80=94for example, an A= PI key and secret for each client. Client credentials are important, becaus= e they enable an organization to provision specific permissions for a clien= t. Don=E2=80=99t confuse client credentials with a person=E2=80=99s credent= ials (i.e., username and password). Person authentication is a very differe= nt requirement from client authentication. People are messy analog carbon-b= ased things. Clients are software. There are fewer options to authenticate = clients than people.
In some flows, the= authorization server may also need to authenticate a person, who then dire= ctly authorizes a client. For example, if you=E2=80=99ve used Google login = from a third-party website, after authenticating (unless you are already lo= gged into Google) you are presented with a dialog asking you to authorize t= his client to call an API that will release information about you, as shown= in Figure 4-3.
Figure 4-3
GA sample Google aut= horization dialog
A quick aside=E2=80=94one important t= hing to note is that in Figure 4-3, you can see the URL of the authorization server=E2=80=94 http= s://accounts.google.com . This is especially important when you a= re entering your credentials. You should never share your password with a <= span id=3D"ITerm11">third-party website, and you should always make = sure that the certificates are valid. Most modern browsers will help you ou= t here. If the little lock icon in the address bar is not green, be concern= ed. Even if it is green, you may not be safe=E2=80=94check the hostname and= make sure it=E2=80=99s one that you trust (easier said than done, for sure= ...) This pattern should remind you of SAML, where you are redirected to th= e IDP to enter your credentials. An OAuth based flow adds an extra step for= authorization.
Getting back to OAuth rol= es, the resource owner is the person who is res= ponsible for making the authorization decision. When you use Google login a= t a third-party site, you are the resource owner=E2=80=94you control access= to your information. In an enterprise IAM setting, the resource owner is t= he organization that manages the RS and AS. For example, an organization ma= y make policies about which people, or which partners may access a certain = API or website.
The other two people (not= software components) in Figure 4-2 are the developer and= the requesting party. Developers are active pa= rticipants in the OAuth infrastructure because they obtain client credentia= ls that are used in their software. The requesting party is the person who = is using a software client to access a protected resource. The requesting p= arty is optional. A machine-to-machine API does not require a requesting pa= rty.
The primary job of the authorization= server is to evaluate policies that enable it = to issue tokens. To accomplish this, clients and resource servers interact = with APIs (or endpoints) published by the authorization server. Two endpoin= ts defined by the OAuth RFC are the authorization and token endpoints. The = authorization endpoint is where a client sends a person using a browser to = interact with an authorization server. The token endpoint is used only by O= Auth clients to obtain or refresh a bearer token. For example, using the Go= ogle sign-in flow again as an example, the first redirect to the authorizat= ion endpoint displays a dialog, such as the one shown in Figure 4-3<= /a>. If you authorize the request, the client will call the token en= dpoint next to obtain an access token, with which it can call an API on a r= esource server.
The authorization server = may publish other OAuth endpoints, depending on what profiles of OAuth it i= mplements. Like LDAP and SAML, OAuth is defined by several related standard= s. An authorization server may implement some optional= interfaces for client registration, token introspection (a way to o= btain information about a particular token) or discovery information (simil= ar to SAML metadata).

Resource Server

The resource server =20 =20 , acting as the policy enforcement point, plays a crit= ical role in the security of the OAuth infrastructure. Its job is to make s= ure a valid token is present=E2=80=94that the token is not expired and that= it has been authorized for the correct scopes. The resource server will al= so need to understand how to use the various types of tokens. In some cases= , the resource server must itself call APIs of the authorization server=E2= =80=94to validate a token, for example.

T= he resource server will want to minimize external calls and the processing = time to decrypt tokens. For this reason, many resource server implementatio= ns cache tokens to expedite subsequent authorization for the same token val= ue.

The developer who writes a resource s= erver will have to coordinate with the administrators of the authorization = server regarding what policies are in place to issue tokens for certain sco= pes. Sometimes the same group controls both the authorization server and re= source servers. In other cases, the authorization server might be in contro= l of the central access management team. This is the reason that Google pub= lishes the scopes that are required to call its APIs, as shown in Figure 4-1.

The resource server = will have to decide which policies to delegate to the authorization server.= =E2=80=9CThe user has approved access=E2=80=9D is the most common policy f= or consumer OAuth applications. But using UMA, a protocol that builds on OA= uth (the topic of Chapter 8), you can map scopes to enterprise access policies.=

Centralized policy = management =20 =20 is a useful approach but it=E2=80=99s not a silver bu= llet. In general, centralized policy management works well for coarse-grain= authorization, but not for fine-grain authorization. In a web application,= what to display on a certain page is normally controlled by =E2=80=9Cfine-= grained=E2=80=9D permissions. Coarse-grained policies are shared across mor= e than one application. For example, what type of authentication is require= d, which internal roles can access which types of applications, which softw= are clients to trust=E2=80=94implementing these policies in every applicati= on would lead to code duplication.

Client

An OAuth client is the softw= are that calls the protected resource. It is frequently connected to a pers= on=E2=80=94the requesting party. The client obtains a token from the author= ization server and presents it to the resource server. In many cases, it=E2= =80=99s the job of the client developer to obtain client credentials at the= authorization server and to know what scopes are needed to access the reso= urce server. The client may need to process a redirect to enable the reques= ting party to interact with the authorization server. The client may also n= eed to handle errors that are returned by either the authorization server o= r the resource server.

Clients may be a w= ebsite or native application. In some cases, the client may even be a JavaS= cript application that exists entirely in the person=E2=80=99s browser. It= =E2=80=99s important to remember that the client is not the same as the bro= wser. The browser is software that the requesting party uses to access the = Internet. SAML jargon =E2=80=9Cuser agent=E2=80=9D applies here too. The cl= ient is software that is between the browser and the protected resource.

In machine-to-machine transactions, where t= here is no requesting party, the policies must apply only to information ab= out the client and the context of the transaction. For example, is this cli= ent (authenticated with a client_id and secret), calling from this network,= during this time of day, authorized to obtain a token for certain scopes? = A certain group of clients may be associated with a certain partner or cate= gory of applications=E2=80=94such information about the client is called a = =E2=80=9Cclient claim=E2=80=9D and is different from user claims about the = requesting party.

To= kens
A token= is an abstraction that represents permission by the authorization server t= o do something. An access token is a short-live= d token that is obtained by the client. A refresh token is a long-lived tok= en that is presented by the client to the authorization server in exchange = for a new access token. =E2=80=9CShort-lived=E2=80=9D means one hour or les= s, but actual times may vary depending on the policy of the authorization s= erver. One to five minutes are common lengths for the lifetime of an access= token.
The authorization server decides = what type of token to return. Each access token type definition specifies t= he additional attributes (if any) sent to the client along with the access = token. The client should not use a token if it does not understand the toke= n type. Each token has a different security profile and is useful for diffe= rent use cases. Long strings are frequently used as bearer tokens. OAuth pr= ovides a mechanism where additional token types= can be registered as extensions. JSON Web Tokens (JWTs)=E2=80=94pronounced= =E2=80=9Cjots=E2=80=9D=E2=80=94are popular, and are sometimes used as the = bearer token string. There is also an extension for something called =E2=80= =9CMAC=E2=80=9D tokens. These are tokens that enable the client to protect = the access token value and are useful for non-secure communication channels= . However, due to the widespread use of TLS for OAuth, MAC tokens =20 aren=E2=80=99t used that much in enterprise deployments= , so we=E2=80=99ll skip discussion of these tokens.
Bearer Tokens
RFC 6570, =E2=80=9CURI Template,=E2=80=9D = describes bearer =20 token usage in OAuth. A bearer token is any data stru= cture that gives the possessor rights to do something=E2=80=94without requi= ring the owner of the token to verify control of a cryptographic key. A bea= rer token can be a string of sufficient entropy to make guessing unlikely.<= /p>
It can also be an XML or JSON document en= coded appropriately. OAuth relies heavily on bearer tokens, but SAML IDPs a= lso commonly use them=E2=80=94i.e., signed SAML assertions. It is imperativ= e to the security of any access management infrastructure based on bearer t= okens to prevent an attacker from gaining possession of the token during tr= ansmission, in memory, or on the disk. If this happens, game over! The reso= urce server has no way to distinguish the attacker from the authorized toke= n owner!
Listing 4-1 i= s a simple example of an OAuth bearer token returned from an authorization = server.
HTTP/1.1 200 OK
Content-T= ype: application/json;charset=3DUTF-8
Cache-C= ontrol: no-store
Pragma: no-cache
{
"access_token": "4190276= 8-ae84-4a1c-8e62-566a8605b90f",
"token_type":= "Bearer",
"expires_in": 3600,
"refresh_token": "d1d50489-98ac-4d21-9ddb-2358caf835c3"
}
=
Listing 4-1
OAuth Token Endpoint Response
The most common way for a client = to send a bearer token to the resource server is to include the token in th= e Authorization header field, although RFC 6570 also defines mechanisms to = send the access token as an HTML form encoded body parameter or in the URI = (which is a bad idea). Using the header, the bearer token would look like t= his:
Authorization: Bearer 41902768-ae84-4a1c-8e62-566a8605b90f=
In simple OAuth implementations =20 , where the resource server and authorization server a= re the same, the resource server might make a query to the local database t= o retrieve information about a bearer token=E2=80=94for example, when does = it expire or for what scopes was it authorized? If the authorization server= is remote, RFC 7662 defines an API for =E2=80=9Ctoken introspection=E2=80= =9D. This provides a mechanism for the resource server to retrieve a JSON o= bject from the authorization server that describes the token. Listing 4-2 is an example from RFC 7662 of a response to the introspect= ion API.
HTTP/1.1 200 OK
Content-= Type: application/json
{
"active": true,
"client_id": "l238j323ds-23ij4",
"username": "jdoe",
"= scope": "read write dolphin",
"sub": "Z= 5O3upPC88QrAjx00dis",
"aud": "https://p= rotected.example.net/resource",
"iss": = "https://server.example.com/",
"exp": 1= 419356238,
"iat": 1419350238,
"extension_field": "twenty-seven"
} =20 =20 =20
<= div class=3D"CaptionContent">Listing 4-2
Sample OAuth Token Introspsection Response
JSON Web Token (JWT)
Defined in RFC 7519, the JWT token type is essentially a compact syntax to send an optionally signed and e= ncrypted JSON object. It=E2=80=99s surprisingly compact on the wire=E2=80= =94you may even be able to send it as a query parameter. The token can cont= ain user claims and can eliminate the need for token introspection. JWT tok= ens are also particularly advantageous in stat= eless web architectures. Another application for JWT is where cookies can= =E2=80=99t be used, for example, due to restrictions on writing third-party= cookies.
JSON Web Tokens consist of th= ree sections, separated by two periods:
Header.Payload.Signatur= e
The header describes the cryptographic algori= thms used for signing and encryption, for example: {"alg": "RS256"}. If you want t= o know the meaning of =E2=80=9CRS256,=E2=80=9D you need to check RFC 7518, = which describes JSON web algorithms. If you don=E2=80=99t want to use any e= ncryption or signing in your JWT, you can use {"alg":"none"}. In this case, there would be= no text after the second period=E2=80=94you=E2=80=99d just have a header a= nd payload. The header may also be used to send unencrypted claims. Note th= at the value of any substantive unencrypted claims should be verified again= st the signed JSON payload.
The JSON payload portion of the token may have three types = of claims: reserved, public, and private. The reserved claims are the ones = defined in the OAuth specifications, such as iss (issuer), exp (expiration time), sub (subject), and aud (audience). Public claims are = registered at the IANA JSON Web Token Registry or are collision-resistant U= RIs. Private claims are ad hoc claims agreed upon by the organizations usin= g them.
Validation of the signature is too complex for treatment here. The token can be = encrypted, signed, signed and encrypted, or encrypted and signed. If encryp= ted, the client would have to previously register its public key with the a= uthorization server. For signing, public keys of the authorization server a= re frequently provided on a URL for download. OAuth supports many different= signing and encryption algorithms. As mentioned, check RFC 7518 for a full= list. Then, check to make sure these are supported on the authorization se= rver.
Proof-of-Possession Tokens
= A proof-of-possession token, also called a hold= er-of-key (HoK) token =20 , requires control of a cryptographic key to provide= additional evidence that the presenter of the token is the party to whom t= he token was issued. This approach mitigates the risk of stolen tokens. RFC= 7800 introduces how to declare in a JWT that the presenter of the JWT poss= esses a particular proof-of-possession private key and how the recipient ca= n cryptographically confirm this. Thus, a JWT can be either a bearer token = or a proof-of-possession token.
Token Binding
Token binding is an adv= anced topic that is still under development, and whose future is not 100% c= ertain, as adoption by websites and browsers has been slow. The Google team= has even discussed the possibility of dropping support for it, although ho= pefully they=E2=80=99ll keep the feature. The idea is for the browser to ge= nerate a public key, private key, and an identifier (Token Binding Key) for= TLS connections to a web server. These keys and identifiers are long-lived= . When a connection is made between the browser and website, the identifier= can be remembered at the website. When issuing a security token (e.g., an = HTTP cookie or an OAuth token) to a client, the server can include the Toke= n Binding ID in the token, thus cryptographically binding the token to TLS = connections between that client and server, as well as inoculating the toke= n against abuse (re-use, attempted impersonation, etc.) by attackers. This = would protect the token from man-in-the-middle, token export, and replay at= tacks.
In a typical OAuth session, there = are several TLS connections: between the browser and AS, between the browse= r and RS, between the client and AS, and even between the RS and AS. There = are several opportunities to use token binding to improve security. The ini= tial work addresses how to protect OAuth access tokens and refresh tokens f= or TLS connections between the client and AS.
Token binding could be a useful tool to pr= event man-in-the-middle attacks, and its use has been proposed for banking = and financial services profiles. An alternative to token binding is mutual = TLS, for which another OAuth draft is under development.
Registration
The authorization= server needs to know information about each client before it can issue the= client a token. This is similar to SAML, where the IDP needs to configure = trust for each SP. What is new in OAuth =20 =20 is a standardized option for self-service registratio= n. In SAML, the IDP administrator generally imports the SP=E2=80=99s metada= ta or configures information about the SP. This is usually a manual process= , although sometimes a website may create a proprietary process for self-pr= ovisioning. OAuth registration defines standards for client provisioning. D= uring registration, the client is issued a client identifier. At a minimum,= the client must tell the AS the URIs where it is okay to send users after = the AS has finished its interaction=E2=80=94the redirect_uris. This is impo= rtant because the AS should never redirect a person=E2=80=99s browser to a = URI that has not been previously registered. If the redirect_uri is a web a= ddress, it must always use the https scheme, and the AS must validate the T= LS certificate or certificate keychain. Frequently, the authorization colle= cts other information about the client such as a name, an icon, a URL of th= e home page, a link to the privacy policy, and a brief description of the a= pplication. The client may also register an asymmetric client secret. Clien= t registration =20 =20 is also an appropriate time for the client to notify = the AS about its preferences. What types of cryptographic algorithms are pr= eferred? What scopes are requested? What are the default user authenticatio= n mechanisms desired? All this information may be provided during registrat= ion.
Although the API and vocabulary fo= r registration can align to OAuth standards, the business process may still= vary. The developer may need to complete a form, sign a legal agreement, o= r provide various pieces of information about their organization. Sometimes= , the client credentials are automatically created and available for use. F= or example, the OpenID Connect profile of OAuth defines an API that enables= a client developer to automatically register. Figure 4-4= shows Google=E2=80=99s very minimal client registration page
Figure 4-4
Google client registration form =20 =20
RFC 7591 defines common conventions around dynamic c= lient registration, including client metadata fields and details about the = client registration endpoint. Also discussed is registration with software = statements.
It is required that the AS = return the client_id in the registration response (see Listing 4-3). A client_secret is also frequently returned. Aaron Parecki list= s some common OAuth client_ids on his informative site, http= ://oauth.com .
Foursquare: ZYDPLLBWSK3MVQJ= SIYHB1OR2JXCY0X2C5UJ2QAR2MAAIT5Q
Github: 6779= ef20e75817b79602
Google: 292085223830.apps.go= ogleusercontent.com
Instagram: f2a1ed52710d45= 33bde25be6da03b6e3
SoundCloud: 269d98e4922fb3= 895e9ae2108cbb5064
Windows Live: 00000000400E= CB04
Gluu: @!AA77.E41E.1889.6F5E!0001!09FB.4F= BB!0008!3CDC.3AF4
Listing 4-3
Sample client_id Values from Popular Consumer IDPs
The combined client_id a= nd client_secret should be stronger than a person=E2=80=99s username and pa= ssword. In the security considerations section of the core OAuth authorizat= ion framework section, guidelines are given to prevent credential-guessing = attacks for the size of access tokens, authorization codes, refresh tokens,= resource owner passwords =20 =20 , and client credentials. It states:
Note
The probability of = an attacker guessing generated tokens (and other credentials not intended f= or handling by end-users) MUST be less than or equal to 2^(-128) and SHOULD= be less than or equal to 2^(-160).
If you have trouble computing those huge numbers, it=E2=80=99s about 1 in = 340 undecillion to 1.5 quindecillion (give or take a few billion). That=E2= =80=99s a number with 38-48 zeros at the end. How you can accomplish this i= s beyond my mathematical capabilities. See Listing 4-3 for= some good examples.
Grants
The process or method by which a client obtains an access= token is called an authorization grant =20 =20 =20 . The grant represents a permission for the client to ac= cess an API endpoint. Each type of authorization grant has a different flow= with its own security characteristics. Following is a description of the d= ifferent grants, and when their use is appropriate. Figure 4-5 presents a flowchart to help explain when you use each grant type.
Figure 4-5
Grant type flowchart
Authorization Code Grant
This flow, for web-based client applications =20 , uses a =E2=80=9Ccode=E2=80=9D (a guess resistant str= ing) to represent a person=E2=80=99s delegation to the client. The code is = returned to the person=E2=80=99s browser and is forwarded to the client, wh= o exchanges it (with client credentials) for a token or tokens. The code ca= n only be used once, which reduces the risk of it leaking. Figure 4-= 6 provides a sequence diagram for a common use case for the auth= orization code grant=E2=80=94how it can be used as the basis for a login fl= ow.
Like SAML, this grant uses browser = redirects to enable a person to interact with a central security server. In= Figure 4-6, the login form and the authorization form mi= ght confuse you=E2=80=94what=E2=80=99s the difference? The login form is wh= ere the person enters their username and password or uses another authentic= ation technology (e.g., token or biometric). The person uses the authorizat= ion form to approve some action. Figure 4-3 shows an auth= orization where the person authorizes the release of information to a third= party. Before enabling you to authorize, the AS may need to authenticate w= ho you are, then it can enable you to authorize something.
Figure 4-6
Sequence diagram for an authorization code grant<= /span> =20 based login flow
It=E2=80=99s important that the cod= e be protected and that it=E2=80=99s sufficiently long to prevent guessing.= However, because the code is passed through the browser, it=E2=80=99s stil= l susceptible to interception by existing malware. If additional security i= s needed, there is an extra security step that can be implemented called Pr= oof Key for Code Exchange (PKCE, pronounced =E2=80=9Cpixy=E2=80=9D) by OAut= h public clients, described in RFC 7636. Using this mitigation technique, t= he client adds a nonce to the authorization request. If the code is interce= pted, without this extra nonce, it cannot be exchanged for a token =20 .
Implicit Grant
JavaScript client applications have become very popular and= powerful. Sometimes these applications act as OAuth clients. This presents= an interesting security challenge because the client is contained in the b= rowser, so there is no point using an authorization code to hide the token= =E2=80=94the browser will end up seeing it anyway when it executes the Java= Script! Another consideration is that only front-channel communication can = be used=E2=80=94the AS has no direct way to communicate with the client (ba= ck-channel).
The Implicit Grant =20 was designed to accommodate this use case. It enables= a JavaScript client to request an access token without a client secret, di= rectly from the authorization URI. For this reason, the Implicit Grant has = less security protection. The redirect_uri requested by the client is prere= gistered with the AS (as normal), which is the main security mechanism. It= =E2=80=99s also worth noting that the client cannot obtain a refresh token = using this flow (because the client cannot call the token endpoint, which r= equires client authentication).
Figure = 4-7 provides a sample sequence diagram for an Implicit Gr= ant based login flow. When the access token is returned by the server, it i= s appended to the redirect_uri as a fragment. It might look something like = this:
GET /client-callback#access_token=3D8027ad39-9316-49d5-9b= 3b-10cce3e9b02d&token_type=3DBearer HTTP/1.1
Figure 4-7
Sequence diagram for an implicit grant-based login flow =20
Resource Owner Password Credential Grant
Can=E2=80=99t you just validate username/password credentials at= the authorization server, like you can with an LDAP BIND operation? The Resource Owner Password Credential Grant =20 =20 lets a client do just that, posting both client crede= ntials and the person=E2=80=99s credentials at the token endpoint to obtain= an access token. One disadvantage of this grant is that all communication = is performed on the back channel by the client, so the authorization server= will not be able to write any cookie or session information in the browser= (defeating many single sign-on implementations). Of course, the biggest di= sadvantage of this flow is that the client sees the person=E2=80=99s passwo= rd. This flow should be vehemently discouraged=E2=80=94it is the OAuth anti= -pattern. It should only be used where there is a supreme amount of trust i= n the client. And even then, the client developers should be encouraged to = use either the Authorization Code Flow (for web or mobile applications) or = implicit flow (for JavaScript client applications). Listing 4-4 shows a sample request (with client credentials sent as Basic).
POST /token
  Host: trusted_= client.example.local
  Accept: appl= ication/json
  Content-type: applic= ation/x-www-form-encoded
  Authoriz= ation: Basic 32c0992ae4194701a12dc7440d513d45
  grant_type=3Dpassword&username=3Dfoo&password=3Dspam&a= mp;scope=3Duid
Listing 4-4
Sample Resource Owner Password Credential= Grant =20 =20 Request
=
Client Credential Grant
Probably = the simplest grant type, the client gains an ac= cess token by just providing its own credentials. It=E2=80=99s a useful gra= nt type for machine-to-machine use cases where = there is no person associated with an API request. It=E2=80=99s so simple, = I=E2=80=99ll just show the sample request and response from RFC 6749 (see Listings 4-5 and 4-6<= /span>).
POST /token HTTP/1.1
Hos= t: server.example.com
Authorization: Basic cz= ZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: appl= ication/x-www-form-urlencoded
grant_type=3Dclient_credentials
Listing 4-5
Sample Request
HTTP/1.1 200 OK
&nb= sp;Content-Type: application/json;charset=3DUTF-8
  Cache-Control: no-store
&nbs= p; Pragma: no-cache
  {
  "access_= token":"2YotnFZFEjr1zCsicMWpAA",
  = "token_type":"example",
  "expires_= in":3600,
  "example_parameter":"ex= ample_value"
  } =20 =20 =20
<= div class=3D"CaptionContent">Listing 4-6
Sample Response

Token Introspection

If a reso= urce server receives an access token issued by = an external authorization server, it needs some way to understand what the = access token means. Is it still valid? When was it issued? For what scopes = was it authorized? Sometimes this information is available in a shared data= base. Encoded JWT tokens are sometimes used as access tokens. But if the be= arer token value is only a reference identifier, RFC 7662 describes a mecha= nism where a resource server can request information about it. This process= is called =E2=80=9Ctoken introspection=E2=80=9D. It's a simple flow. Listi= ngs 4-7 and 4-8 show the sample introsp= ection request and response from the RFC.
POST /introspect HTT= P/1.1
Host: server.example.com
Accept: application/json
Cont= ent-Type: application/x-www-form-urlencoded
A= uthorization: Bearer 23410913-abewfq.123483
token=3D2YotnFZFEjr1zCsicMWpAA
Listing 4-7
Sample Request=

HTTP/1.1 200 OK

Content-Type: application/json

{

"active": true,

= "client_id": "l= 238j323ds-23ij4",

"us= ername": "jdoe",

"sco= pe": "read write dolphin",

= "sub": "Z5O3upPC88QrAjx00dis",

&n= bsp; "aud": "https://protected.example.net/resource",

"iss": "https://server.example.= com/",

"exp": 1419356= 238,

"iat": 141935023= 8,

"extension_field":= "twenty-seven"

}

Listing 4-8
Sample Response

RFC 7662 says the = RS must authenticate to introspect a token to prevent a token scanning atta= ck. This normally happens by presenting an OAuth token or by including basi= c client credentials. Given the entropy and short lifetime of access tokens= , you could allow unauthenticated responses if you understand the risks.

If the token is valid, the active response = claim is true. If the token is not valid, it should be false, and no other = information should be returned. RFC 7662 defines some standard claims, but = a domain may use any claims. If the intention is to use token claims across= domains, they should be registered with IANA.<= /p>

OAuth Client Example: Calling a Google API

=
Enough theory, let=E2=80=99s work on an exam= ple of using Google=E2=80=99s free open source Python client library to cal= l an OAuth protected API=E2=80=94in this case Google=E2=80=99s URL shortening service. In subsequent chapters, we cover in= more detail how to use OAuth to protect enterprise resources=E2=80=94how t= o configure a resource server and authorization server for your organizatio= n. Google has a lot of APIs, and their policies and pr= ocedures are typical of a well-run application service.
This chapter uses a sample project called =E2=80=9Cu= rlias=E2=80=9D (like alias for a URL). It will submit a long URL and get ba= ck from Google a shorter URL that can be used for tracking. For example, if= you post a blog and want to know how many people click on your blog, it is= convenient to use a tracking URL. The sample code will be in Python, but t= he process will be the same across any platform. The code is available in t= he GitHub repository for this book.
Obtaining Client Credentials
Remember that each authorization server wi= ll have its own policies and procedures for obtaining = client credentials. Google has a website that enables you to enroll = (agree to the terms of services) and to automatically register your applica= tion, and in the process, obtain client credentials. Start this process by = opening http= s://console.developers.google.com in your browser.
In the Library tab, search for URL= , as shown in Figure 4-8.
Figure 4-8
Searching Goog= le libraries for URL shortener
After clicking on the URL Sh= ortener API, you=E2=80=99ll need to enable it, as shown in Figure <= span class=3D"InternalRef">4-9.
Figure 4-9
Enabling Google URL shortener
=
Google d= oes not offer a dynamic client registration API, so you=E2=80=99ll need to = manually register your client in the dashboard. First, you=E2=80=99ll need = to set up some general properties, like the name, contact information, and = logo of your application, which Google will use to render the OAuth consent= notification. Note that the values shown in Figure 4-10= are just an example. You would use information appropriate to your applica= tion.
Figure = 4-10
Configuring =20 =20 Google OAuth consent screen
Click on the Credentia= ls tab, then on Create Credentials. Then choose OAuth = Client ID, as shown in Figure 4-11.
Figure 4-11
Creating a Google OAuth client ID
T= he form to create client credentials is actually rather short. To create a = web client, there are only three pieces of information you need to supply: = the application type, name, and redirect_uris, as shown in Figure 4= -12.
Figure 4-12
Google clie= nt ID request form
If successful, you should see a modal window with yo= ur client credentials=E2=80=94record these in a secure place. You should ne= ver share your client credentials. Hypothetical= examples are shown in Figure 4-13.
Figure 4-13
Final client credentials
Calling the Google API
Now that= you have client credentials, it=E2=80=99s time to call the API. To show th= is I=E2=80=99d like to reference a sample node project called google-oauth-implicit-example in my GitHub project for this book at http= s://github.com/GluuFederation/iam-book . This is a two-page application: page on= e displays a login button that enables the user to authorize the use of the= ir Google account; page two is a JavaScript applicatio= n that uses the returned access token to call the API. Figure <= span class=3D"InternalRef">4-14 shows the sequence diagram for this application.
Figure 4-14=
Sequence diagram for URL short= ener application

To run this application, you=E2=80=99ll need node.js installed on your = workstation or server. Follow the relevant instructions on http= ://nodejs.org for your operating system. After cloning= the project from GitHub, the first thing you=E2=80=99ll need to do is to s= et the properties files, called settings.js, to enter the client credentials retrieved in = the preceding steps (see Listing 4-9). Don=E2=80=99t forg= et to quote the strings and to use a semicolon at the end of each line. Jus= t as an example, setti= ngs.js should look something like Listing 4-9 (aga= in, those are not real Google API creds.). Note that the callback must matc= h the one you registered for this client with Google. For this demo, I was = running the server on port 8000, but you can choose any free port on your s= ystem.
exports.client_id =3D '6fb8.apps.googleuserc= ontent.com';
exports.client_secret =3D ' ghoe= g&qecyic8_1';
exports.port =3D 8000;
exports.redirectURIPath =3D '/cb';
exports.redirectURI =3D 'http://localhost:8000/cb';
Listing 4-9
Sample Pr= operties for URL Shortener Application (Shorten= ed for Display)
To download the necessary libraries and run the application, navigate via = the command line to the project folder and run the commands shown in Listin= g 4-10.
$ npm install
$ node app
Server Started on port 80= 00
Listing 4-10
Starting the Node Application
=
It might be confusing at first a= s to why the callback works using localhost. Ho= w can Google call back to localhost? The simple answer is that Google gets = your browser to call the callback. So as long as you can connect to http://localhost:8000,= you=E2=80=99re fine. Also, if you=E2=80=99re using localhost, you don=E2= =80=99t need to use https=E2=80=94the traffic is not traversing the network= . If you are redirecting over to anywhere other than localhost, then https = is highly recommended. The client must protect the access token, so using a= non-encrypted protocol would be unwise, even on your local network.
To test the application, point your browser a= t http://localhost:800= 0. You should see the very simple web page shown in Figure 4-15.
=
Figure 4-15
Page o= ne of the URL shortener application
When you click on the button, you may be pro= mpted to log in to Google if you don=E2=80=99t already have a session in yo= ur browser. Once Google knows who you are, you will be asked to authorize t= he client and then will be redirected to page two, shown in Figure = 4-16.
Figure 4-16
Authorizat= ion and page two of the URL shortener application*

The app is simple: ent= er a URL and it will obtain a Google-shortened version for you. The action = of calling the API actually happens in the JavaScript in the browser, which= uses the access token returned in the URL fragment (a fragment is content = returned in a URL after the #). The callback URL and fragment in Figure 4-16 is:
http://localhost:8000/cb#state=3Durlshortenapicall&a= mp;access_token=3Dya29.Ci-
UAzies3LBs9mMLOIZr= 8Sp_iYMgkxTE5aTT3wb6ymyPIccIx-hS8h-
Hlrjlx6f8= Q&token_type=3DBearer&expires_in=3D3599

Parameter	Reference	Des= cription
code	RFC 67= 49	Authorization Code Flow
token	RFC 6749	Implicit Flow

Parameter	= Reference	Description
invalid_request	RFC 67= 50	The request is missing a required parameter, includes = an unsupported parameter or parameter value, repeats the same parameter, us= es more than one method for including an access token, or is otherwise malf= ormed. The resource server SHOULD respond with the HTTP 400 (Bad Request) s= tatus code.
invalid_token	RFC 67= 50	The access token provided is expired, revoked, malform= ed, or invalid for other reasons. The resource SHOULD respond with the HTTP= 401 (Unauthorized) status code. The client MAY request a new access token = and retry the protected resource request.
insufficient_scope	RFC 67= 50	The request requires high= er privileges than provided by the access token. The resource server SHOULD= respond with the HTTP 403 (Forbidden) status code and MAY include the "scope" attribute w= ith the scope necessary to access the protected resource.
unsupported_token_type	RFC 70= 09	The authorization server does not support the revocati= on of the presented token type. That is, the client tried to revoke an acce= ss token on a server not supporting this feature. If the server responds wi= th HTTP status code 503, the client must assume the token still exists and = may retry after a reasonable delay.
unauthorized_client	RFC 67= 49	The client is not authorized to request an authorizati= on code using this method.
access_denied	RFC 67= 49	The resource owner or authorization server denied the = request.
unsupported_response_type	RFC 67= 49	The authorization server does not support obtaining an= authorization code using this method.
invalid_scope	RFC 67= 49	The requested scope is invalid, unknown, or malformed.=
server_error	RFC 67= 49	The authorization server = encountered an unexpected condition that prevented it from fulfilling the r= equest. (This error code is needed because a 500 Internal Server Error HTTP= status code cannot be returned to the client via an HTTP redirect.)
temporarily_unavailable	RFC 67= 49	The authorization server is currently unable to handle= the request due to a temporary overloading or maintenance of the server. (= This error code is needed because a 503 Service Unavailable HTTP status cod= e cannot be returned to the client via an HTTP redirect.)
invalid_client	RFC 67= 49	Client authentication failed.
invalid_grant	RFC 67= 49	The provided authorization grant or refresh token is i= nvalid, expired, revoked, does not match the redirection URI used in the au= thorization request, or was issued to another client.
invalid_scope	RFC 6749	The requested scope is invalid, unkno= wn, malformed, or exceeds the scope granted by the resource owner.

Parameter	Parameter Usage Location	Reference	Description
client_id	author= ization request, token request	RFC 6749	The client identifier issued to the client dur= ing the registration process.
client_secret	token = request	RFC 6749	A string with sufficient entropy to prevent a credential guessing att= ack.
response_type	author= ization request	RFC 6749 <= /td>	The expected response from the authorization endpoint, can = be 'code', 'token', or other r= egistered extension values. =20 =20
redirect_uri	author= ization request, token request	RFC 6749	After completing its interaction with the reso= urce owner, the authorization server redirects the user-agent to this URI.<= /p>
scope	author= ization request, authorization response, token request, token response <= /td>	RFC 6749	The pe= rmissions associated with the access token.
= state	author= ization request, authorization response	RFC 6749	An opaque value used by the client to= maintain state between the request and callback. The authorization server = includes this value when redirecting the user-agent back to the client. The= parameter SHOULD be used for preventing cross-site request forgery.
code	author= ization response, token request	RFC 6749	A string generated by the authorization serve= r that=E2=80=99s used by the client to obtain tokens. It should be short-li= ved (less than 10 minutes), one-time use, and bound to a client-id.
error	author= ization response, token response	RFC 6749	A single ASCII error code specified in the O= Auth Extensions Error Registry.
error_description	author= ization response, token response	RFC 6749	Human-readable ASCII [USASCII] text providin= g additional information, used to assist the client developer in understand= ing the error that occurred.
error_uri	author= ization response, token response	RFC 6749	A URI identifying a human-readable web page = with information about the error, used to provide the client.
grant_type	token = request	RFC 6749	Credential representing the resource owner's authorization (to access= its protected resources) used by the client to obtain an access token. =
access_token	author= ization response, token response	RFC 6749	A string denoting a specific scope, lifetime= , and other access attributes.
token_type	author= ization response, token response	RFC 6749	Information the client needs to successfully= utilize the access token.
expires_in	author= ization response, token response	RFC 6749	The lifetime in seconds of the access token.= For example, the value =E2=80=9C3600=E2=80=9D denotes that the access token will expire i= n one hour from the time the response was generated.
username	token = request	RFC 6749	The identifier for the resource owner.
password	token = request	RFC 6749	The resource owner=E2=80=99s ASCII secret.
refresh_token	token = request, token response	RFC 6= 749	A token that can be used to obtain a new access token= from the authorization server.
assertion	token = request	RFC 7521	A package of information that facilitates the sharing of identity and= security information across security domains.
client_assertion	token = request	RFC 7521	An assertion about the client.
client_assertion_type	token = request	RFC 7521	The format of the assertion.
code_verifier	token = request	RFC 7636	A cryptographically random string that is used to correlate the autho= rization request to the token request.
code_challenge	author= ization request	RFC 7636 <= /td>	A challenge derived from the code verifier that is sent in = the authorization request, to be verified against later.
authorization request	RFC 7636	A mechanism that was used to derive code cha= llenge.

Parameter	Reference	Descri= ption
none	RFC 75= 91	No authentication.
client_secret_post	RFC 75= 91	The client uses the HTTP POST parameters as defined in OAuth 2.0, Sec= tion 2.3.1.
client_secret_basic	RFC 7591	HTTP Basic authentication.

Paramet= er	Reference	Description
active	RFC 76= 62	Token active status.
username	RFC 76= 62	User identifier of the resource owner.
client_id	RFC 76= 62	Client identifier of the client.
scope	RFC 76= 62	Authorized scopes of the token.
token_type	RFC 76= 62	Type of the token.
exp	RFC 76= 62	Expiration timestamp of the token.
RFC 76= 62	Issuance timestamp of the token.
nbf	RFC 76= 62	Timestamp before which the token is not valid.
sub	RFC 76= 62	Subject of the token.
<= p class=3D"SimplePara"> aud	RFC 76= 62	Audience of the token.
= iss	RFC 76= 62	Issuer of the token.
jti	RFC 7662	Unique identifier of the token.

Parameter	Refere= nce	Description
iss	RFC 75= 19	Issuer
sub	RFC 75= 19	Subject
aud	RFC 75= 19	Audience
exp	RFC 75= 19	Expiration Time
nbf	RFC 75= 19	Not Before
iat	RFC 75= 19	Issued At
jti	RFC 75= 19	JWT ID
cnf	RFC 7800	Confirmation

Parameter	= Reference	Description
jwk	RFC 78= 00	JSON Web Key Representing Public Key
jwe	RFC 78= 00	Encrypted JSON Web Key
= kid	RFC 78= 00	Key Identifier
jku	RFC 7800	JWK Set URL =20 =20

Table of Contents for =20 Securing the Perimeter: Deploying Identity and Access Management with= Free Open Source Software =20

4.&n= bsp;OAuth

Scopes

OAuth Roles

Authorization Server

Resource Server

Client

To= kens

JSON Web Token (JWT)

Proof-of-Possession Tokens

Token Binding

Registration

Note

Grants

Authorization Code Grant

Implicit Grant

Resource Owner Password Credential Grant

Client Credential Grant

Token Introspection

OAuth Client Example: Calling a Google API

Calling the Google API

Client Credential Grant Example with the Gluu= Server

Configuring the Gluu = Server

OAuth Glo= ssary and IANA Registry Terms

Conclusion

Reference= s

Highlight

Highlight

Table of Contents for
=20 Securing the Perimeter: Deploying Identity and Access Management with= Free Open Source Software =20